# Development Guide

## **Routing Debugging Tips:**
Mobroute is tested both via unit tests & manually against a number of
actual GTFS sources noted in the README. That said, if you're performing
routing requests on different untested GTFS source and/or with different
params you may get an error if your params are too strict or the GTFS
source data is invalid, here's a number of things you can check:

- **GTFS Source Validity**:
  - Run: `mobroute dbstatus -f '{mdbid: [YOURMDBIDHERE]}'`
  - Check that the `status` field is set to `active`. If its not that means
    the Mobility Database has this flagged as a non-active feed and likely is
    unusable for routing.
  - Paste the `url` field into the [GTFS Validator](https://gtfs-validator.mobilitydata.org/)
    and note any issues. If there are substantial issues, this is not likely a
    feed usable for routing.
- **Routing Parameters Relaxing**:
  - There are pragmatic defaults set for maximum walk / transfer seconds, but
    relaxing these values may help in debugging.
  - Set `max_walk_seconds` and `max_transfer_seconds` to some arbitrarily high
    value such as `99999999999`
- **Routing Debugging via Logs**:
  - Look at the logs for the routing request
  - Observe the line that says: `CSA Begin: xxx conns, yyy transfers, zzz walks origin...`
  - The number for that line should be non-0 for each item
  - If you see zeros; you can pull the SQL statements and run them manually
    to debug further
- **Pay attention to size of the GTFS archives**:
  - While there are no strict limits on the size of GTFS archives for import,
    in practice smaller sized archives will import and route faster ofcourse.
    Archives with stop_times.txt in the range of hundreds of megabytes have
    been tested and route successfully, YMMV with *very* large archives such
    as entire country GTFS aggregates (such as the Germany feed).
  - In logs you can check the MB size logged in GTFS file imports based on
    Mobsql; size is proporotional to import time.
  - Additonally, for compute cycles its helpful to understand the checksum logged
    in the line `Computed table X for source (Y Z) out of date - updating` will
    include the archive sizes as well in the form of `C_XXXM_SHA`, wherein XXX
    is the number of megabytes the source GTFS source file was.
- **Debugging via SQLite DB**:
  - Run `sqlite3 ~/.cache/mobroute/sqlite.db`
  - One example, check that the calendar for today actually produces dates: `
    - `select * from _vcaltoservice where service_date = 20231220 and source = 1898`
- **Clear Cache**:
  - If working with multiple sources and you paused the load process, it might
    not be a bad idea to clear the cache wholesale and retry again.
  - Run: `rm -rf ~/.cache/mobroute`

## **Algorithm:**

The core of the routing system is based on the Connection Scan Algorithm
methodology.  See the following papers for more details:

- [2013 Original CSA Paper](https://i11www.iti.kit.edu/extra/publications/dpsw-isftr-13.pdf)
- [2017 Followup CSA Paper](https://arxiv.org/pdf/1703.05997.pdf)


## **Glossary:**

These abbreviations are used in the sourcecode, note explanation belows:

| Term | Abbreviation | Explanation |
| ---- | ------------ | ------- |
| **IDU** | ID Ultimate | In SQL queries and routing we distinguish between source stop_id's and the 'ultimate' parent stop. A stop IDU refers to a stops.txt entry with no parent in hierarchy. |
| **SIDU** | Source ID Ultimate | Essential IDU but also prefixed with the source e.g. as "{SOURCE}_{IDU}". |
| **MDBID**: | Mobility Database ID | Source ID from pulled from the [Mobility Database Catalog](https://github.com/MobilityData/mobility-database-catalogs). |
| **Source** | Eventually will refer to a system independent representation of the imported GTFS source; for now source is always equal to MDBID. |
